
cmake_minimum_required(VERSION 3.30)

# CMake 项目命令喵

message("\n======================================================================")
message("  --  项目命令喵，文档喵")
message("======================================================================\n")

add_subdirectory(Sample) # 示例项目喵

# █████████████████████████████████████████████████████████████████████████████
#      --    作用范围喵
# █████████████████████████████████████████████████████████████████████████████

# <INTERFACE|PUBLIC|PRIVATE> 用于指定作用范围喵
#   INTERFACE 表示用于指定项目的使用方
#   PUBLIC 表示用于指定项目及其使用方
#   PRIVATE 表示仅用于指定的项目

# █████████████████████████████████████████████████████████████████████████████
#      --    目标喵
# █████████████████████████████████████████████████████████████████████████████

# =============================================================================
# 可执行文件喵

# 普通可执行文件喵
# add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [source1] [source2 ...])

# 导入的可执行文件喵
# add_executable(<name> IMPORTED [GLOBAL])

# 可执行文件的别名喵
# add_executable(<name> ALIAS <target>)

# =============================================================================
# 库喵

# 普通库喵
# add_library(<name> [STATIC|SHARED|MODULE] [EXCLUDE_FROM_ALL] [<source>...])
#   STATIC 为静态库， SHARED 为动态库， MODULE 为运行时库，指定 EXCLUDE_FROM_ALL 则排除在生成过程中

# 导入库，从外部导入库喵
# add_library(<name> <STATIC|SHARED|MODULE|UNKNOWN|OBJECT> IMPORTED [GLOBAL])
#   指定 GLOBAL 则全局可见

# 接口库喵，不会编译和生成，可用以安装和导出，比如纯头文件库
# add_library(<name> INTERFACE) 

# 对象库喵，编译但不链接
# add_library(<name> OBJECT [<source>...]) 

# 库的别名喵
# add_library(<name> ALIAS <target>)

# =============================================================================
# 链接喵

# 将库链接到以后添加的所有目标喵
# link_libraries([item1 [item2 [...]]] [[debug|optimized|general] <item>] ...)

# 链接目标 target 和 item
# target_link_libraries(<target> ... <item>... ...)

# =============================================================================
# 源文件喵

# 查找目录中的所有源文件喵
# aux_source_directory(<dir> <variable>)

# 向目标添加源文件喵
# target_sources(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

# █████████████████████████████████████████████████████████████████████████████
#      --    预处理宏定义喵
# █████████████████████████████████████████████████████████████████████████████

# 添加预处理宏定义喵，前导的 -D 将被删除
# add_compile_definitions(<definition> ...)

# 为一个目标添加宏定义喵，前导的 -D 将被删除，目标必须由 add_executable 或 add_library 创建，不能是 ALIAS target
# target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

# █████████████████████████████████████████████████████████████████████████████
#      --    目录喵
# █████████████████████████████████████████████████████████████████████████████

# 添加到全局的包含目录列表 INCLUDE_DIRECTORIES ，指定 SYSTEM 则目录在某些平台为系统包含目录
# include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])

# 添加到全局的库目录列表 LINK_DIRECTORIES
# link_directories([AFTER|BEFORE] dir1 [dir2 ...])

# 指定目标的包含目录，指定 SYSTEM 则目录在某些平台为系统包含目录
# target_include_directories(<target> [SYSTEM] [AFTER|BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

# 指定目标库目录喵
# target_link_directories(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

#   AFTER 和 BEFORE 指定添加位置（末尾和头部）

# █████████████████████████████████████████████████████████████████████████████
#      --    依赖喵
# █████████████████████████████████████████████████████████████████████████████

# 添加依赖项可以保证被依赖项总是先生成喵
# add_dependencies(<target> [<target-dependency>]...)

# █████████████████████████████████████████████████████████████████████████████
#      --    安装喵
# █████████████████████████████████████████████████████████████████████████████

# 通用选项喵
# [DESTINATION <dir>] # 安装文件的目标目录喵
# [PERMISSIONS permissions...] # 安装文件的权限喵，可为 OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE SETUID SETGID
# [CONFIGURATIONS [Debug|Release|...]] # 为之后出现的项指定配置喵
# [COMPONENT <component>] # 指定组件名称喵
# [OPTIONAL] # 要安装的文件不存在则不报错喵
# [EXCLUDE_FROM_ALL] # 从完整安装中排除，仅作为组件特定安装的一部分安装
# [RUNTIME_DEPENDENCY_SET <set-name>] # 将依赖项添加到指定的运行时依赖集中。可使用 install(RUNTIME_DEPENDENCY_SET) 命令安装依赖集

# 安装目标喵
# install(TARGETS targets... # 安装的目标喵
#   [EXPORT <export-name>] # 将目标导出为 export-name
#   [RUNTIME_DEPENDENCIES args...| # 同时安装目标的所有运行时依赖项
#     RUNTIME_DEPENDENCY_SET <set-name>]
#   [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI] # 安装项的类型
#     [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL]
#     [NAMELINK_COMPONENT <component>] # 指定组件的符号链接名称
#     [NAMELINK_ONLY|NAMELINK_SKIP] # 符号链接
#   ] [...]
#   [INCLUDES DESTINATION [<dir> ...]]) # 同时将指定目录添加到项目的 INTERFACE_INCLUDE_DIRECTORIES 中

# 安装导入的运行时组件喵
# install(IMPORTED_RUNTIME_ARTIFACTS targets... # 安装的组件喵
#   [RUNTIME_DEPENDENCY_SET <set-name>]
#   [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] # 安装项的类型喵
#     [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL]
#   ] [...])

# 安装文件喵
# install(<FILES|PROGRAMS> files... # 安装的文件喵
#   TYPE <type> | DESTINATION <dir> # 文件类型或安装位置喵，提供类型时将根据类型自行选择位置
#   [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL]
#   [RENAME <name>]) # 将文件重命名

# 安装目录喵
# install(DIRECTORY dirs...
#   TYPE <type> | DESTINATION <dir> # 文件类型或安装位置喵，提供类型时将根据类型自行选择位置
#   [FILE_PERMISSIONS permissions...] # 文件权限
#   [DIRECTORY_PERMISSIONS permissions...] # 文件夹权限
#   [USE_SOURCE_PERMISSIONS] # 使用源文件的权限
#   [MESSAGE_NEVER] # 安装时不输出消息
#   [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL]
#   [FILES_MATCHING] # 仅安装通过过滤的文件
#   [[PATTERN <pattern> | REGEX <regex>] # 文件过滤选择
#     [EXCLUDE] # 跳过匹配的文件
#     [PERMISSIONS permissions...] # 文件的权限
#   ] [...])

# 自定义安装逻辑喵
# install([[SCRIPT <file>] # 调用给定的 CMake 脚本文件
#   [CODE <code>]] # 调用给定的 CMake 代码
#   [ALL_COMPONENTS | COMPONENT <component>] # 为哪些组件执行此逻辑
#   [EXCLUDE_FROM_ALL] [...])

# 安装导出喵
# install(EXPORT <export-name> # 安装的导出
#   DESTINATION <dir> [PERMISSIONS permissions...]
#   [NAMESPACE <namespace>] # 命名空间
#   [FILE <name>.cmake] # 文件名
#   [CONFIGURATIONS [Debug|Release|...] [COMPONENT <component>] [EXCLUDE_FROM_ALL]
#   [CXX_MODULES_DIRECTORY <directory>] # 保存 C++ 模块的目录
#   [EXPORT_LINK_INTERFACE_LIBRARIES]) # 导出 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? 命名的属性的内容

# 安装运行时依赖喵
# install(RUNTIME_DEPENDENCY_SET <set-name> # 安装的依赖集合
#   [[LIBRARY|RUNTIME|FRAMEWORK] # 依赖类型
#    [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL]
#    [NAMELINK_COMPONENT <component>] # 指定组件的符号链接名称
#   ] [...]
#   [PRE_INCLUDE_REGEXES regexes...] [PRE_EXCLUDE_REGEXES regexes...] [POST_INCLUDE_REGEXES regexes...] [POST_EXCLUDE_REGEXES regexes...] [POST_INCLUDE_FILES files...] [POST_EXCLUDE_FILES files...] [DIRECTORIES directories...]) # 由 file(GET_RUNTIME_DEPENDENCIES) 使用

# █████████████████████████████████████████████████████████████████████████████
#      --    导出喵
# █████████████████████████████████████████████████████████████████████████████

# 导出目标喵
# export(TARGETS <target>... [NAMESPACE <namespace>] # 目标名和命名空间喵
#   [APPEND] # 指定则为追加，否则为覆盖喵
#   FILE <filename> # 导出的文件名喵
#   [EXPORT_LINK_INTERFACE_LIBRARIES] # 在导出中包含以模式 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? 命名的属性的内容
#   [CXX_MODULES_DIRECTORY <directory>]) # 将 C++ 模块属性导出到给定目录下的文件中

# 导出导出喵，创建一个文件 <filename> ，外部项目可以通过包含该文件，从当前项目中导入目标
# export(EXPORT <export-name> [NAMESPACE <namespace>] # 导出名和命名空间喵
#   [FILE <filename>] # 导出的文件名喵
#   [CXX_MODULES_DIRECTORY <directory>] # 将 C++ 模块属性导出到给定目录下的文件中
#   [EXPORT_PACKAGE_DEPENDENCIES]) # 由 find_dependency() 使用喵

# 导出包喵，但是默认不操作喵喵
# export(PACKAGE <PackageName>)

# 配置导出喵，配置导出的参数
# export(SETUP <export-name> # 要配置的导出名称
#   [PACKAGE_DEPENDENCY <dep> # 依赖
#     [ENABLED (<bool-true>|<bool-false>|AUTO)] # 控制是否导出依赖关系
#     [EXTRA_ARGS <args>...] # 传递给 find_dependency 的附加参数
#   ] [...]
#   [TARGET <target> # 导出的目标
#     [XCFRAMEWORK_LOCATION <location>] # 疑似 XCode 使用
#   ] [...])

# █████████████████████████████████████████████████████████████████████████████
#      --    编译链接选项喵
# █████████████████████████████████████████████████████████████████████████████

# 向目标添加预编译头文件喵
# target_precompile_headers(<target> <INTERFACE|PUBLIC|PRIVATE> [header1...] [...])

# 添加全局编译选项喵，如 W4 : warning level 4
# add_compile_options(<option> ...)

# 为目标添加编译选项喵
# target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

# 向目标添加链接选项喵
# target_link_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [...])

# 向目标添加编译特性喵，如 -std=gnu++11 等
# target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])

# █████████████████████████████████████████████████████████████████████████████
#      --    自定义编译链接步骤喵
# █████████████████████████████████████████████████████████████████████████████

# =============================================================================
# 自定义命令喵

# 用于生成输出文件喵
# add_custom_command(OUTPUT output1 [output2 ...] # 输出文件喵
#   COMMAND command1 [ARGS] [args1...] # 命令和参数喵
#   [COMMAND command2 [ARGS] [args2...] ...] # 命令和参数喵
#   [MAIN_DEPENDENCY depend] # 指定命令的主要输入源文件喵
#   [DEPENDS [depends...]] # 依赖文件喵
#   [BYPRODUCTS [files...]] # 指定命令预期生成的文件喵
#   [IMPLICIT_DEPENDS <lang1> depend1 [<lang2> depend2] ...] # 隐式依赖喵
#   [WORKING_DIRECTORY dir] # 执行目录喵
#   [COMMENT comment] # 执行命令前输出的提示信息喵
#   [DEPFILE depfile] # 依赖文件喵
#   [JOB_POOL job_pool] # Ninja 生成器相关
#   [JOB_SERVER_AWARE <bool>] # 命令是 GNU Make job server aware
#   [VERBATIM] [APPEND] [USES_TERMINAL] # VERBATIM 保证了命令参数的字面意义喵； APPEND 将 COMMAND 和 DEPENDS 选项值附加到指定第一个输出的自定义命令喵； USES_TERMINAL 授予直接访问终端的权限喵
#   [CODEGEN] # 添加到代码生成器全局目标喵
#   [COMMAND_EXPAND_LISTS] # 命令参数中的列表将被扩展喵
#   [DEPENDS_EXPLICIT_ONLY]) # 指示命令的 DEPENDS 参数表示命令所需的所有文件，并且不需要隐式依赖关系

# 用于建立事件喵
# add_custom_command(TARGET <target> # 目标喵
#   PRE_BUILD | PRE_LINK | POST_BUILD # 执行时机喵
#   COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] # 命令和参数喵
#   [BYPRODUCTS [files...]] # 指定命令预期生成的文件喵
#   [WORKING_DIRECTORY dir] # 工作目录喵
#   [COMMENT comment] # 执行命令前输出的提示信息喵
#   [VERBATIM] # 保证了命令参数的字面意义喵
#   [COMMAND_EXPAND_LISTS] # 命令参数中的列表将被扩展喵
#   [USES_TERMINAL]) # 授予直接访问终端的权限喵

# =============================================================================
# 自定义目标喵

# 添加一个自定义的目标，每次都会重新构建喵
# add_custom_target(Name # 目标名称喵
#   [ALL] # 指明这个目标应该被添加到默认的构建目标中，每次都会运行
#   [command1 [args1...]] # 构建时执行的命令喵
#   [COMMAND command2 [args2...] ...]  # 构建时执行的命令喵
#   [DEPENDS depend depend depend ... ] # 依赖文件喵
#   [BYPRODUCTS [files...]] # 指定命令预期生成的文件喵
#   [WORKING_DIRECTORY dir] # 工作目录喵
#   [COMMENT comment] # 执行命令前输出的提示信息喵
#   [JOB_POOL job_pool] # Ninja 生成器相关
#   [JOB_SERVER_AWARE <bool>] # 命令是 GNU Make job server aware
#   [VERBATIM] [USES_TERMINAL] # VERBATIM 保证了命令参数的字面意义喵； USES_TERMINAL 授予直接访问终端的权限喵
#   [COMMAND_EXPAND_LISTS] # 命令参数中的列表将被扩展喵
#   [SOURCES src1 [src2...]]) # 源文件喵
